﻿using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace Common
{
    public interface IActiveList
    {
        /// <summary>
        /// Adds the given token to the list, keeping track of the lowest scoring token
        /// </summary>
        /// <param name="token">token the token to add</param>
        void add(IToken token);
        /// <summary>
        /// Replaces an old token with a new token
        /// </summary>
        /// <param name="oldToken">the token to replace (or null in which case, replace works like add).</param>
        /// <param name="newToken">the new token to be placed in the list.</param>
        void replace(IToken oldToken, IToken newToken);
        /// <summary>
        /// Purges the active list of excess members returning a (potentially new) active list
        /// </summary>
        /// <returns>a purged active list</returns>
        IActiveList purge();
        /// <summary>
        /// Returns the size of this list
        /// </summary>
        /// <returns>the size</returns>
        int size();

        /// <summary>
        /// Gets the list of all tokens 
        /// </summary>
        /// <returns>set of tokens</returns>
        List<IToken> getTokens();

        /// <summary>
        /// gets the beam threshold best upon the best scoring token
        /// </summary>
        /// <returns>the beam threshold</returns>
        float getBeamThreshold();
        /// <summary>
        /// gets the best score in the list
        /// </summary>
        /// <returns>the best score</returns>
        float getBestScore();

        /// <summary>
        /// Sets the best scoring token for this active list
        /// </summary>
        /// <param name="token">token the best scoring token</param>
        void setBestToken(IToken token);

        /// <summary>
        /// Gets the best scoring token for this active list
        /// </summary>
        /// <returns>the best scoring token</returns>
        IToken getBestToken();

        /// <summary>
        /// Creates a new empty version of this active list with the same general properties.
        /// </summary>
        /// <returns>a new active list.</returns>
        IActiveList newInstance();
    }
}
